Parameter Data Behavior

The Parameter Data Behavior atom contains user interface hints that suggest to the client application how a parameter should be displayed.

Note
These user interface hints can be ignored by your application if you have a specific interface style you wish to implement. However, Apple recommends that you use the editing mechanisms suggested for the parameter whenever possible. If your application does not use the suggested behavior, you will present an inconsistent and potentially confusing interface to your users.

typedef struct
{
    QTAtomID    groupID;
    long        controlValue;
} ControlBehaviors;


typedef struct
{
    OSType  behaviorType;
    long    behaviorFlags;
    union
    {
        ControlBehaviorscontrols;
    } u;
} ParameterDataBehavior;


behaviorType

This field contains a value that specifies a user interface for editing the parameter's value. This field should contain one of the following pre-defined values:

kParameterItemEditText

- the parameter should be edited using an edit text field.

kParameterItemEditLong

- the parameter should be edited using an edit text field that only accepts numerical entries.

kParameterItemEditFixed

- the parameter should be edited using an edit text field that accepts floating-point numerical entries.

kParameterItemPopUp

- the parameter should be edited using a pop-up menu. This data behavior should only be used with parameters whose data type is kParameterTypeDataEnum ; the pop-up menu is populated from the enumeration values.

kParameterItemRadioCluster

- the parameter should be edited using a group of radio buttons. This data behavior should only be used with parameters whose data type is kParameterTypeDataEnum ; the radio buttons are created from the enumeration values

kParameterItemCheckBox

- the parameter should be edited using a checkbox This data behavior should only be used with parameters whose data type is kParameterTypeDataBitField .

kParameterItemControl

- the parameter should be edited using a standard control appropriate to the data type of the parameter. For parameters that accept a scalar value, such as a Fixed or a Long , the control used is a slider.

kParameterItemLine

- a horizontal line is drawn in above the control that manipulates this parameter's value.

kParameterItemRectangle

- a rectangle is drawn around the control that manipulates this parameter's value.

kParameterItemColorPicker

- the parameter should be edited using a color swatch and picker.

kParameterItemGroupDivider

- start of a new group of items.

kParameterItemStaticText

- the parameter's name is displayed as a static text field.

kParameterItemDragImage

- the parameter should be edited as an image that accepts drag and drop entry of new images.

kParameterItemDragPath

- the parameter should be edited as a path display that allows the user to drag out a new path.

behaviorFlags

This field can take one or more of the following values:

kGraphicsNoFlags - no options for graphics.

kGraphicsFlagsGray - any lines or rectangles that are drawn have a grayscale

appearance. If this option is not set, lines and rectangles are drawn in black.

kGroupNoFlags - no options for the group.

kGroupAlignText - the controls in the group are aligned.

kGroupSurroundBox

- the controls in the group are surrounded with a box.

kGroupMatrix

- display the controls in the group in a matrix, if such an arrangement is possible.

kGroupNoName - do not display the name of the group.

The following behaviorFlags values allow you to optionally show or hide a group depending on the value entered into a parameter. This allows you to express simple conditionals within a standard parameters dialog box. For example, you may want a pop-up menu with a set of fixed options, and an 'Others...' option; if the user chooses 'others', a text edit field is enabled to allow users to enter their own value.

To do this, you can use the kDisableWhenLessThan flag to specify that the group containing the text control is disabled when the user chooses any value in the pop-up menu that is less than the last, 'Others...' option.

The following flags are available to control selective disabling of groups. For each of these flags, the ID of the group to be disabled is stored in the groupID field of the controls data structure. The value that is used in the comparison operation is stored in the controlValue field of the controls data structure.

kDisableWhenNotEqual

- When the value chosen for this parameter is not equal to

controlValue , disable the group groupID .

kDisableWhenEqual

- When the value chosen for this parameter is equal to

controlValue , disable the group groupID .

kDisableWhenLessThan

- When the value chosen for this parameter is less than the

controlValue , disable the group groupID .

kDisableWhenGreaterThan

- When the value chosen for this parameter is greater than

the controlValue , disable the group groupID .

Note
You can only disable groups, not individual parameters. However, you can create a group with no visual attributes that contains a single parameter.

The parameter data behavior atom is required.

---

© 1999 Apple Computer, Inc.

| Previous | Chapter Contents | Chapter Top | Next |